User Guide for Ian Reed's Adventure Game Engine

Overview

Thanks for trying my adventure game engine. The ShadowGate adventure created by Nina0116 is the only completed adventure for the engine. It's a port of the original ShadowGate game on the Nintendo Entertainment System. Despite the difficulties of working with the scripting engine Nina0116 has done a great job with this adventure. Congratulations Nina0116! I also want to thank Allan Thompson for his help in testing the game. Testing can be quite time consuming and he has my appreciation for his effort.

An explanation of adventure games

An adventure game generally consists of you being the main character and exploring the game through inspecting, taking, using, talking, and combining various objects. In the sighted world this is done through displaying locations as images and allowing the player to point and click with either an eye, hand, mouth, walk, or item cursor. In the audio gaming world these same actions are supported via menus. the BAVISoft games Grizzly Gulch and ChillingHam are the best examples of audio versions of these games.

Basic Keys

• Up / Down = move through menu items.
• Right / Left = Adjust sliders in menus.
• Enter / Space bar = Activate the current selection.
• Escape = Cancel the current action.
• Home, End = Move to the top or bottom item in a menu.
• F2 = Speak the current menu or dialog caption.
• F3 = Announce current menu item.

The following keys are only available once you have started the ShadowGate adventure.

• shift + I = Jump to inspect menu.
• shift + T = Jump to Take menu.
• shift + U = Jump to use menu.
• shift + K = Jump to talk menu.
• shift + S = Jump to the select menu where you can select an inventory item to use or combine with another item or object.
• shift + G = Jump to the go menu.
• tab and shift + tab = cycle through the action menus when in an action menu. When in the select action it will cycle through the items in your inventory.
• tilde or control + G = Launches the game menu which allows you to change audio settings and save or load your game.

Other helpful keys

• Control + L = Launch notepad with the last 50 spoken items in the speech log.
• F1 = Launch this user guide in your web browser.
• F11 = Raise music volume.
• shift + F11 = lower music volume.
• F12 = Mute or unmute music. This can be helpful if you want to leave the game open while you do something else on your computer and need the music muted.
• Right bracket (]) = Speech rate up.
• Shift + Right bracket (]) = Speech rate down.
• Backslash = Speak next line in the speech log.
• Shift + Backslash = Speak previous line in the speech log.

First letter navigation in menus

It's worth noting that you can press the first letter of a menu item to quickly jump to that item in the menu. This can be a big time saver when your inventory gets large.

Creating your own adventure

Creating your own adventure is a challenging and time consuming task. It requires you to be able to write code which means you'll need to understand the basics of programming or scripting.

Unlike my Tactical Battle game which allows map creation without any scripting the Adventure Game Engine relies very heavily on scripting. It gives you all the power that comes with writing code and all the heart ache as well.

That said, AGE does present a very friendly way of defining locations, objects and menus. That coupled with the engine handling all the low level tasks of managing the current state, playing music, playing sounds and supporting saving and loading out of the box gives you a huge headstart for writing your own games in this genre. If you're interested in writing your own adventure read the rest of this manual and definitely write me an email to let me know. My email is support@BlindAudioGames.com.

The Data for AG folder

In the Data for AG folder you will find 3 interesting folders.

• Adventures, where you can add a new folder that contains your adventure.
• Menus, where you can see examples of how the main menu and game menu are defined.
• Scripts, where I have some global scripts

One of the best ways to learn is by looking at examples. Start by looking at the Main Menu.txt file to see how the Play ShadowGate by nina0116 menu item was defined. Next you would go find the Start Menu.txt file in the Adventures\Shadowgate\Menus folder to see how that works. From there you can see that the Start Game menu item references the outside shadowgate.txt file defined in the locations folder. You can continue following the code to see how things work and play along in the game as well.

Location files

Each location file has the following format.

• line 1 should always say location
• line 2 defines the parser version and should always be 1 for now.
• line 3 defines the caption which is what gets spoken when you enter that location or if you press F2 while in the location.
• Line 4 is spoken if you inspect the location.
• line 5 is used for flags of which there are none right now.
• line 6 is used to list all the locations you can visit from the current location, they are separated by spaces and any locations that have spaces in their names should have the spaces replaced by underscores.
• line 7 lists all the objects that initially appear in this location

Object files

Each object file has the following format.

• line 1 should always say object
• line 2 defines the parser version which is always 1 for now.
• line 3 is for flags of which the only flag currently available is "takeable"
• line 4 and onward define an action that could be taken on the object and the text that is spoken when that action is taken.

Actions are inspect, use, take, and talk. You can also specify what happens if you use an object in your inventory on this object. For example, if you are in the bucket file and want to define what happens when the rope is used on the bucket it would look like this:

• rope |@ combine_rope_and_bucket();

You can also put the word inv in front of actions to indicate that this text is only spoken if the action is performed on the object while it is in your inventory. In this way you could have inspect and inv inspect as you might get a more informative message about something when it is in your inventory. For example, if we are in the silver ring file we might define these actions:

• inspect | It's a pretty silver ring.
• inv inspect | It's a pretty silver ring. On closer inspection you notice an inscription with the initials I.R. Who could that belong to?

Adding the takeable flag tells the engine that it should handle removing the item from the location and placing it in the inventory when the player attempts to take it. This saves unnecessary scripting for a common task such as taking items.

Notes on scripting

The engine uses javascript as the scripting language. I've tried to simplify how to define core parts of the game like locations and objects by using a custom file format for each. Within these files you can sometimes specify that you want to run a script rather than just have the text spoken. For example in a well object file you might have the following line:

• rope and bucket |@ use_rope_and_bucket_on_well();

The @ sign after the | indicates that you want to run javascript instead of speaking the text. So in this scenario whenever a player uses the rope and bucket object on the well it will run the javascript to the right of the @ sign.

After all the action lines in a location or object you will often see a line with a single @ sign on it. This indicates that the rest of the file is javascript. This is a good place to define a function such as use_rope_and_bucket_on_well. Then you can have all your code at the bottom of files and little snippets of code to call your functions on the action lines.

There are many examples in the ShadowGate files, look through them to see some of the things you can do.

When the game says there is a script error you can read the error in the Data for AG\ScriptError.txt file.

Scripting functions

Here is a list of the functions that the engine exposes to the Javascript. Note that built in Javascript functions such as Math.random are also available. I've put example parameters in each of the functions below to give a feel for how the function would be used. If you have questions please contact me at support@BlindAudioGames.com.

• say("Hello");
• music("beautiful song.mp3");
• stopMusic();
• sound("big bang.wav");
• stopSound("wind.mp3");
• stopAllSounds();
• loadAdventure("ShadowGate"); // where ShadowGate is the name of the folder the adventure is in, this can also be used to restart the adventure from the beginning as it sets locations and inventory back to their default state.
• context("Outside ShadowGate"); // takes you to a location or menu with the name specified.
• createItem("rope"); // creates an item from the objects folder in the current location or in the inventory depending upon which is currently open.
• destroyItem("rope"); // destroys an item in the current location or in the inventory depending upon which is currently open.
• createInventoryItem("rope"); // creates an item in your inventory.
• destroyInventoryItem("rope"); // destroys an item in your inventory
• getInventoryItem("rope"); // returns an inventory object or null, you can check if this is null to determine if you have the specified item or not.
• createLocationItem("rope"); // creates an item in the current location.
• destroyLocationItem("rope"); // destroys an item in the current location.
• getLocationItem("rope"); // returns an object in the current location or null, you can check if this is null to determine if the object exists in the current location or not.
• addLocation("stone passage"); // adds a location you can visit from the current location. See the unlock_door function in the steel door.txt object file in the ShadowGate game.
• removeLocation("pet store"); // removes a location from the list that you can visit from the current location
• switchToActionMenu(); // returns you to the main action menu with options like inspect, take, use, talk, select, go.
• reloadActionHandler(); // reloads the current action menu, this is useful if you are doing an action on an item and it destroys that item, you then want to reload the action menu so the item does not show up anymore.
• goToActionList(); // Switches to the action list. Useful for returning from a menu.
• elapsedSeconds(); // returns a floating point number of elapsed seconds since the game was launched.
• showOrHideMenuItem(2, global.humana); // shows or hides a menu item based on whether the second parameter is true or false. See the spells menu.txt file in the ShadowGate adventure.

The sound function can also take a second parameter which is a JSON object with certain property specifying options you want. Options have reasonable defaults if you do not set them and as demonstrated above you don't have to pass the options object at all.

• sound("Footsteps outside pyramid.mp3", { end : 4, synchronous : true });

The above function ends the playing of the footsteps sound after 4 seconds, it does this because the sound actually plays for a much longer time if you play the whole thing. synchronous means that the sound will play and the script will wait for it to play before continueing. In this scenario we wanted to play footsteps and wait before more text was spoken. If you wanted the footsteps to play at the same time as more text was spoken you would set synchronous to false or just leave it off all together as false is the default for that option.

• sound("wind.mp3", { repeat : true, restart : false });

Repeat makes it so the sound will play in a loop and never stop. Restart set to false makes it so if the sound is already playing and you come across a script that would play it again it will not restart the sound and just leave it playing the way it was.

Scripting Events

There are 2 scripting events that are useful in location files:

• location_name_onArrive()
• location_name_onLeave()

And 3 events that are useful in menus:

• menu_name_onEnter()
• menu_name_onExit()
• menu_name_onEscape(), occurs when the user presses the escape key.

The onEnter and onExit events should be avoided in location files as they do not correspond to when you arrive in the location and when you leave it which will give undesired behavior. The ShadowGate adventure was written before the onArrive event came into existence which is why it uses the onEnter event in so many places.

Final notes

Thanks for playing AGE and I hope you enjoy Nina0116's ShadowGate adventure. Creating the Adventure Game Engine has been a great learning experience for me. The code I've written and the knowledge I've gained from it will benefit Tactical Battle and future game engines I plan on creating.

Written by Ian Reed